Todd
For W2K platform and R5.0.10
Setting up SSO between Domino and Websphere servers
5.8.2: Configuring SSO for Lotus Domino
To use SSO with Domino and WebSphere Application Server, you must first configure SSO for WebSphere Application Server and then configure SSO for Domino.
Configuring SSO for Domino is accomplished by selecting a new Multi-server option in a Server document for session-based authentication, and by creating a new domainwide configuration document, called the Web SSO Configuration document, in the Domino Directory. The Web SSO Configuration document, which must be replicated to all Domino servers participating in the SSO domain, is encrypted for participating Domino servers and contains a shared secret used by Domino servers for authenticating user credentials.
To provide SSO to Domino servers, do the following:
Create the Web SSO Configuration document.
Configure the Server document.
Finish the Domino configuration.
Verify the SSO for Domino configuration.
In addition, you can optionally do the following:
Configure additional Domino servers in the original domain.
Configure Domino servers in different domains.
To complete this procedure, you need the following information from the configuration of SSO for WebSphere Application Server:
The path and name of the file containing the LTPA keys created during SSO configuration for WebSphere Application Server
The password used to protect the LTPA keys from WebSphere Application Server
The name of DNS domain in which WebSphere Application Server is configured
Create the Web SSO Configuration document
To create the Web SSO Configuration document, use a Lotus Notes Client R5.0.5 (or later) and follow these steps:
1. In the Domino Directory, select the Servers view.
2. Click on the Web pull-down menu item.
3. Select the Create Web SSO Configuration option to create the document.
4. On the Web SSO Configuration document, click the Keys pull-down menu.
5. Select the Import WebSphere LTPA Keys option to import the LTPA keys previously created for WebSphere Application Server and stored in a file.
6. Type the path to the file containing the keys for WebSphere Application Server and click OK.
7. Type the password that was used when generating the LTPA keys. The SSO Configuration document is automatically updated to reflect the information in the imported file.
8. Fill in remaining fields in this document. Groups and wildcards are not allowed in the fields. The following list describes the fields and the expected values:
Token Expiration: The number of minutes a token can exist before expiring.
A token does not expire based on inactivity; it is valid for only the number of minutes specified from the time of issue.
Token Domain: The DNS domain portion of your system's fully qualified Internet name. This is a required field.
All servers participating in SSO must reside in the same DNS domain; this value must be the same as the Domain value specified when configuring WebSphere Application Server. Also, WebSphere Application Server treats the DNS domain as case sensitive, so ensure that the DNS domain value is specified in exactly the same way, including the same case.
Domino Server Names: The Domino servers that will be participating in SSO. This SSO Configuration document will be encrypted for the creator of the document, the members of the Owners and Administrators fields, and the servers specified in this field. These servers can be in different Domino domains; however they must be in the same DNS domain.
You must specify a fully qualified Domino server name, for example, MyDominoServer/MyOu. The Domino server name that you specify here must also match the name of the corresponding server's Connection document in your client's Domino Directory.
LDAP Realm: The fully qualified DNS host name of the LDAP server.
This field is initialized from the information provided in the imported LTPA keys file. You need to change this value only if an port value for the LDAP server was specified for the WebSphere Application Server administrative domain. If a port was specified, a backslash character (\) must be inserted into the value before the colon character (:). For example, replace myhost.mycompany.com:389 with myhost.mycompany.com\:389.
9. Save the Web SSO Configuration document. It now appears in the Web Configurations view.
If you are configuring multiple Domino servers for SSO, refer to Configuring additional Domino servers.
Configure the Server document
To update the Server document for SSO, follow these steps:
1. In the Domino Directory, select the Servers view.
2. Edit the Server document.
3. Select the Ports --> Internet Ports --> Web tab
4. Click the Enable Name & Password Authentication for the HTTP Port box to enable basic authentication for Web users.
5. Select Internet Protocols --> Domino Web Engine.
6. Select Multi-server in the Session Authentication field to enable SSO for Domino.
7. Save the Server document.
If you are configuring multiple Domino servers for SSO, refer to Configuring additional Domino servers.
Finish the Domino configuration
Before continuing, finish configuring the Domino server for use by Web users. The remaining configuration steps are not specific to SSO and are not covered here in detail. Refer to the Domino 5 Administration Help for information on the following:
Configuring access to an LDAP directory when the Domino Directory is not being used
Authorizing Web users to Domino resources
Verify the SSO for Domino configuration
To verify the SSO configuration for Domino, ensure that the Domino server is configured correctly and that Web users are authorized to access Domino resources by performing the following steps:
To verify that the Domino server is configured correctly, stop and restart the Domino HTTP Web server. If SSO is configured correctly, the following message appears on the Domino server console: HTTP: Successfully loaded Web SSO Configuration.
If a Domino server enabled for SSO cannot find a Web SSO Configuration document or is not included in the Domino Server Names field and therefore cannot decrypt the document, the following message appears on your server's console: HTTP: Error Loading Web SSO configuration. Reverting to single-server session authentication.
To verify that users are authorized, attempt to access a Domino resource, such as a Domino Directory, first as a user defined in the Domino Directory itself, for local authorization, and then as a user defined in the LDAP directory service, for authorization of WebSphere Application Server users.
Configure additional Domino servers in a single domain
If you are using SSO with multiple Domino servers, perform the following steps for each additional server:
1. Replicate the initial Web SSO Configuration document to each additional Domino server.
2. Update the Server document for each additional Domino server.
3. Restart each of the Domino HTTP web servers.
Configure Domino servers in multiple Domino domains
If you are using SSO with Domino servers is multiple Domino domains, you must also set up cross-domain authentication among the Domino servers. For example, assume there are Domino servers in two Domino domains, X and Y. Use the following procedure to enable the Domino servers to perform SSO between the domains:
1. A Domino administrator must copy the Web SSO Configuration document from the Domino Directory for Domain X and paste it into the Domino Directory for Domain Y. The Domino administrator needs rights to decrypt the Web SSO Configuration document in Domain X and to create documents in the Domino Directory for Domain Y.
2. Ensure that your Lotus Notes client's location home server is set to a Domino server in Domain Y.
3. Edit the Web SSO Configuration document for Domain Y.
4. In the Participating Domino Servers field, include only the Domino servers with Server documents in Domain Y that will participate in SSO.
5. Save the Web SSO Configuration document. It is now to be encrypted for the participating Domino servers in Domain Y, so these servers now have the same key information as the Domino servers in domain X. This shared information allows Domino servers in Domain Y to perform SSO with Domino servers in Domain X.
5.8.3: Verifying SSO between WebSphere and Domino
This document discusses the verification of SSO between Domino and WebSphere Application Server. Before proceeding, verify that the following conditions are met:
The LDAP directory contains at least one user that is defined for testing purposes.
The WebSphere Application Server administrative console can be started for each of the WebSphere Application Server administrative domains involved in SSO.
A user can authenticate to each administrative domain using a security name defined in the LDAP directory.
At least one user in the LDAP directory must be authorized to access at least one Domino resource, such as the Domino Directory.
At least one user in the LDAP directory must be authorized to access at least one WebSphere Application Server resource, such as the Hello servlet.
From a Web browser that is configured not to accept HTTP cookies, you are able to reach the following resources:
WebSphere-protected resources, like servlets, after being prompted for a user ID and password.
Domino-protected resources, like Lotus Notes databases, after being prompted for a user ID and password.
If all of the preliminary tests succeed, you are ready to verify that SSO is working correctly. To test the SSO functionality, perform the following steps:
1. Restart the Web browser.
2. Configure the Web browser to accept HTTP cookies. (If you are using Internet Explorer, enable the per-session (not stored) type of cookies.
3. Configure the browser to notify you before accepting HTTP cookies. This will provide visual confirmation that Domino and WebSphere Application Server are generating and returning HTTP cookies to your browser after you authenticate. (You can suppress the cookie notifications after you verify that cookies are being exchanged.)
4. From the browser, specify the URL for a resource protected by the Domino server; for example, attempt to open a database that permits no access to anonymous users, as described in the following example:
Make sure to user a fully qualified DNS host name in the URL; for example, enter
http://myhost.mycompany.com/names.nsf instead of
http://myhost/names.nsf.
When prompted for a user ID and password, make sure that you specify a user ID that is authorized to resources for both the Domino and WebSphere application servers.
The format of the name depends on the level of restriction Domino is using for Web users and whether Domino or another LDAP directory is being used. (For details on the options for basic authentication, refer to the Domino 5 Administrative Help; in particular, see the information on controlling the level of authentication for Web clients.) The level of restriction Domino uses for Web users is set in the Web server authentication field on the Security window of the Server document. If you are using the default configuration settings, you can specify the user's short name or user ID.
When prompted, accept the HTTP cookie.
Successfully accessing such a resource verifies that the token generated by the Domino server is accepted by WebSphere Application Server.
5. From the same browser session, attempt to access a resource protected by WebSphere Application Server. If SSO is working correctly, access is granted without prompting you to log in. (If you are prompted, refer to SSO fails when accessing protected resources for assistance.) Make sure to use the fully qualified DNS host name in the URL. For example, type
http://myhost.mycompany.com/webapp/examples/showCfg instead of
http://myhost/webapp/examples/showCfg.
6. From the same browser session, attempt to access resources managed by any additional Domino and WebSphere Application Server domains included in your SSO configuration.
7. Restart your browser session and perform the SSO-verification steps again, but this time, start by accessing a resource protected by WebSphere Application Server. This will verify that the token generated by WebSphere Application Server is accepted by the Domino server or servers. When prompted for a user ID and password, use the user's short name or user ID; this is the default naming convention for users in WebSphere Application Server
5.8.4: Troubleshooting SSO configurations
This article describes common problems in configuring single sign-on between WebSphere Application Server and Domino and suggests possible solutions. The problems include the following:
Failure to save the Domino Web SSO Configuration document
Domino server console fails to load the Web SSO Configuration document upon Domino HTTP server start-up
Authentication fails when accessing a protected resource
Authorization fails when accessing a protected resource
SSO fails when accessing protected resources
Failure to save the Domino Web SSO Configuration document
The client must be able to find Domino Server documents for the participating SSO Domino servers. The Web SSO Configuration document is encrypted for the servers that you specify, so the home server indicated by the client's location record must point to a server in the Domino domain where the participating servers reside. This ensures that lookups can find the public keys of the servers.
If you receive a message that states that one or more of the participating Domino servers cannot be found, then those servers will not be able to decrypt the Web SSO Configuration document or perform SSO.
When the Web SSO Configuration document is saved, the status bar indicates how many public keys were used to encrypt the document by finding the listed servers, authors, and administrators on the document.
Domino server console fails to load the Web SSO Configuration document upon Domino HTTP server startup
During configuration of SSO, the Server document is configured for Multi-Server in the Session Authentication field. Therefore, the Domino HTTP server tries to find and load a Web SSO Configuration document during startup. The Domino server console reports the following if a valid document is found and decrypted:
HTTP: Successfully loaded Web SSO Configuration.
If a server cannot load the Web SSO Configuration document, SSO does not work. Such a server reports the following message:
HTTP: Error Loading Web SSO configuration. Reverting to single-server session authentication.
Make sure that there is only one Web SSO Configuration document in the Web Configurations view of the Domino Directory and in the $WebSSOConfigs hidden view. You cannot create more than one, but additional documents can be inserted during replication.
Check the hidden view $WebSSOConfigs as follows:
1. From a Lotus Notes client, select File --> Database --> Open.
2. In the Open Database dialog, either type the Domino server name and press Enter or select the Domino server from the list.
3. Type the value names.nsf for the FileName field, located at the bottom of the Open Database dialog box. Do not press Enter. Instead, hold the the shift and control keys down and click Open on the dialog box. This opens the Domino Directory with all the hidden views exposed.
4. At the bottom of the view list, click $WebSSOConfigs and ensure there is only one document in this view. If there are more than one, delete them all and re-create the Web SSO Configuration document.
If there is only one Web SSO Configuration document, another condition that can elicit the same error message is that the public key of the Server document does not match the public key in the ID file. In this case, attempts to decrypt the Web SSO Configuration document fail and the error message is generated.
This situation can occur when the ID file is created multiple times but the Server document is not updated correctly. Usually, there is an error message displayed on the Domino Server Console that states that the public key does not match the server ID. If this happens, then SSO does not work because the document is encrypted with a public key for which the server does not possess the corresponding private key.
To correct a key-mismatch problem, do the following:
1. Copy the public key from the server ID file and paste it into the Server document.
2. Re-create the Web SSO Configuration document.
Authentication fails when accessing a protected resource
If a Web user is repeatedly prompted for a user ID and password, SSO is not working because either the Domino or WebSphere security server is not able to authenticate the user with the LDAP server. Check the following possibilities:
Verify that the LDAP server can be accessed from the Domino server machine. Use the TCP/IP ping utility to verify TCP/IP connectivity and that the host machine is running.
Verify that the LDAP user is defined in the LDAP directory. Use the ldapsearch utility to confirm that the user ID exists and that the password is correct. For example, the following command, entered as a single line, can be run from the OS/400 Qshell, a UNIX shell, or a Windows DOS prompt:
% ldapsearch -D "cn=John Doe, ou=Rochester, o=IBM, c=US" -w mypassword
-h myhost.mycompany.com -p 389
-b "ou=Rochester, o=IBM, c=US" (objectclass=*)
(The percent character (%) indicates the prompt and is not part of the command.)
A list of directory entries is expected. Possible error conditions and causes follow:
No such object: This error indicates that the directory entry referenced by either the user's DN value, which is specified after the -D option, or the base DN value, which is specified after the -b option, does not exist.
Invalid credentials: This error indicates that the password is invalid.
Can't contact LDAP server: This error means that the host name or port specified for the server is invalid or that the LDAP server is not running.
An empty list means that the base directory specified by the -b option does not contain any directory entries.
If you are using the user's short name (or user ID) instead of the Distinguished Name, ensure that the directory entry is configured with the short name. For a Domino Directory, this is the Short name/UserID field of the Person document. For other LDAP directories, this is the userid property of the directory entry.
If Domino authentication fails when using an LDAP directory other than Domino Directory, verify the configuration settings of the LDAP server in the Directory Assistance document in the Directory Assistance database. Also verify that the Server document refers to the correct Directory Assistance document.
The following LDAP values specified in the Directory Assistance document must match the values specified for the user registry in the WebSphere administrative domain:
Domain name
LDAP host name
LDAP port
Base DN
Additionally, the rules defined in the Directory Assistance document must refer to the base DN of the directory containing the directory entries of the users.
You can trace the Domino server's requests to the LDAP server by adding the following line to the server's notes.ini file:
webauth_verbose_trace=1
After restarting the Domino server, trace messages are displayed in the Domino server's console as Web users attempt to authenticate to the Domino server.
Authorization fails accessing a protected resource
After authenticating successfully, if a Web user is shown an authorization error message, security is not configured correctly. Check the following possibilities:
For Domino databases, verify that the user is defined in the access-control settings for the database. Refer to the Domino Administrative documentation for the correct way to specify the user's DN. For example, for the DN cn=John Doe, ou=Rochester, o=IBM, c=US, the value on the access-control list must be set as John Doe/Rochester/IBM/US.
For resources protected by WebSphere Application Server, verify that the security permissions are set correctly.
If granting permissions to selected groups, make sure that the user attempting to access the resource is a member of the group. For example, you can verify the members of the groups by using the following URL to display the directory contents: Ldap://myhost.mycompany.com:389/ou=Rochester, o=IBM, c=US??sub
If you have changed the LDAP configuration information (host, port, and base DN) in a WebSphere Application Server administrative domain since the permissions were set, the existing permissions are probably invalid and need to be re-created.
SSO fails when accessing protected resources
If a Web user is prompted to authenticate each time he or she accesses a resource, SSO is not configured correctly. Check the following possibilities:
1. Both WebSphere Application Server and Domino must be configured to use the same LDAP directory. The HTTP cookie used for SSO stores the full Distinguished Name (DN) of the user, for example, cn=John Doe, ou=Rochester, o=IBM, c=US, and the DNS domain.
2. If the Domino Directory is being used, Web users must be defined by hierarchical names. For example, update the User name field in the Person document to include names of this format as the first value: John Doe/Rochester/IBM/US.
3. URLs issued to Domino and WebSphere application servers configured for SSO must specify the full DNS server name, not just the host name or TCP/IP address. For browsers to be able to send cookies to a group of servers, the DNS domain must be included in the cookie, and the DNS domain in the cookie must match the URL. (This is why cookies cannot be used across TCP/IP domains.)
4. Domino and WebSphere Application Server must be configured to use the same DNS domain. Verify that the DNS domain value is exactly the same, including capitalization. The DNS domain value can be found on the Configure Global Security Settings panel of the WebSphere administrative console and in the Web SSO Configuration document of a Domino server. If you make a change to the Domino Web SSO Configuration document, replicate the modified document to all Domino servers participating in SSO.
5. Clustered Domino servers must have the host name populated with the full DNS server name in the Server document for Domino ICM (Internet Cluster Manager) to redirect to cluster members using SSO. If this field is not populated, by default, ICM redirects URLs to clustered Web servers by using only the host name. It cannot send the SSO cookie because the DNS domain is not included in the URL.
To correct the problem, do the following:
a. Edit the Server document.
b. Select the Internet Protocols -- > HTTP tab.
c. Enter the server's full DNS name in the Host names field.
6. If a port value for an LDAP server was specified for a WebSphere Application Server administrative domain, the Domino Web SSO Configuration document must be edited and a backslash character (\)must be inserted into the value of the LDAP Realm field before the colon character (:). For example, replace myhost.mycompany.com:389 with myhost.mycompany.com\:389.
Return to top
. . RE: Need help setting up SSO (~Laura Cisfreel... 4.Feb.03) 
Print this page
